SQLAlchemy migratsioon Alembicuga: skeemiversioonimine selgitatud

Andmebaasi skeemi haldamine on tarkvaraarenduse kriitiline aspekt, eriti projektides, mis aja jooksul arenevad. Rakenduse kasvades ja selle andmenõuete muutudes on vaja usaldusväärset viisi andmebaasi skeemi muutmiseks, ilma et andmed kaoksid või olemasolev funktsionaalsus katkeks. Siin tulevad appi andmebaasi migratsioonid.

SQLAlchemy, populaarne Pythoni SQL-tööriistakomplekt ja objekt-relatsiooniline kaardistaja (ORM), pakub võimsat ja paindlikku viisi andmebaasidega suhtlemiseks. Kuid SQLAlchemy ise ei halda skeemimigratsioone otse. Siin tuleb mängu Alembic. Alembic on kerge ja hõlpsasti kasutatav migratsioonitööriist, mis on spetsiaalselt loodud sujuvaks tööks SQLAlchemy-ga.

See põhjalik juhend tutvustab teile Alembicu kasutamise protsessi SQLAlchemy migratsioonide jaoks, hõlmates kõike alates esmasest seadistamisest kuni arenenud tehnikateni. Olenemata sellest, kas olete kogenud arendaja või alles alustate SQLAlchemy-ga, annab see juhend teile teadmised ja oskused oma andmebaasi skeemi tõhusaks haldamiseks.

Miks kasutada andmebaasi migratsioone?

Enne tehnilistesse detailidesse sukeldumist mõistame, miks andmebaasi migratsioonid on nii olulised:

• Versioonihaldus teie andmebaasile: Migratsioonid võimaldavad teil jälgida andmebaasi skeemi muudatusi versioonihaldussüsteemi põhimõttel, täpselt nagu teie rakenduse koodi puhul. See tähendab, et saate hõlpsasti vajadusel taastada varasema skeemi või rakendada muudatusi järk-järgult.
• Automaatsed skeemivärskendused: Manuaalse SQL-skriptide käivitamise asemel pakuvad migratsioonid automatiseeritud viisi andmebaasi skeemi värskendamiseks. See vähendab vigade riski ja tagab järjepidevuse erinevates keskkondades.
• Koostöö: Migratsioonid hõlbustavad meeskondade koostööd andmebaasi muudatuste osas. Iga arendaja saab luua ja rakendada migratsioone iseseisvalt, ilma et need üksteise tööga konflikti satuksid.
• Juurutamine: Migratsioonid lihtsustavad juurutusprotsessi, pakkudes usaldusväärset viisi andmebaasi skeemi värskendamiseks osana teie rakenduse juurutustorustikust. See tagab, et teie andmebaas on alati teie rakenduse koodiga sünkroonis.
• Andmete säilitamine: Hästi kavandatud migratsioonid aitavad teil andmeid skeemi muudatuste ajal säilitada. Näiteks saate luua migratsiooni, mis lisab uue veeru ja täidab selle andmetega olemasolevast veerust.

Alembicu seadistamine SQLAlchemy-ga

Alustame Alembicu seadistamisest teie SQLAlchemy projektis. Eeldame, et teil on juba Pythoni projekt, milles SQLAlchemy on installitud.

1. Installige Alembic

Kõigepealt installige Alembic, kasutades pip-i:

            pip install alembic
            

              
                Copy
              
            
          

2. Initsialiseerige Alembic

Liikuge oma projekti juurkataloogi ja käivitage Alembicu initsialiseerimiseks järgmine käsk:

            alembic init alembic
            

              
                Copy
              
            
          

See loob teie projekti uue kataloogi nimega `alembic`. See kataloog sisaldab Alembicu konfiguratsioonifaili (`alembic.ini`) ja kataloogi `versions`, kuhu salvestatakse teie migratsiooniskriptid.

3. Konfigureerige Alembic

Avage fail `alembic.ini` ja konfigureerige säte `sqlalchemy.url`, et see osutaks teie andmebaasi ühendusstringile. Näiteks:

            sqlalchemy.url = postgresql://user:password@host:port/database
            

              
                Copy
              
            
          

Asendage `user`, `password`, `host`, `port` ja `database` oma tegelike andmebaasi mandaatidega. Kaaluge keskkonnamuutujate kasutamist tundlike mandaatide salvestamiseks, selle asemel et need otse faili sisse kirjutada. See on eriti oluline koostööprojektides või erinevatesse keskkondadesse juurutamisel.

Järgmiseks avage fail `alembic/env.py` ja konfigureerige Alembic ühenduma teie SQLAlchemy mootoriga. Fail `env.py` on Alembicu integreerimise tuum SQLAlchemy-ga. See vastutab andmebaasi ühenduse loomise, olemasoleva skeemi peegeldamise (kui see on olemas) ja migratsiooniskriptide genereerimise konteksti pakkumise eest.

Leidke funktsioon `run_migrations_online` ja muutke seda nii, et see kasutaks teie SQLAlchemy mootorit. Siin on näide:

            def run_migrations_online():
    """Run migrations in a 'live' settings.

    This hook is provided to run migrations using a direct
    database connection.

    Instead of an Engine, the connectable within the
    configuration context is already a Connection.
    """
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata
        )

        with context.begin_transaction():
            context.run_migrations()

            

              
                Copy
              
            
          

Veenduge, et `target_metadata` on seadistatud teie SQLAlchemy metaandmete objektile. See annab Alembicule teada, milliseid tabeleid ja skeeme hallata. Näide:

            from myapp.models import Base
target_metadata = Base.metadata

            

              
                Copy
              
            
          

Selles näites eeldatakse, et `myapp.models` on moodul, kus teie SQLAlchemy mudelid on defineeritud, ja `Base` on teie mudelite deklaratiivne baasklass.

4. Looge oma esimene migratsioon

Nüüd, kui Alembic on seadistatud, saate luua oma esimese migratsiooni. Alembic suudab automaatselt tuvastada muutused teie mudelites ja genereerida migratsioone, või saate neid luua käsitsi keerulisemate stsenaariumide korral.

Automaatne migratsiooni genereerimine

Oma praeguste SQLAlchemy mudelite põhjal migratsiooni automaatseks genereerimiseks käivitage järgmine käsk:

            alembic revision --autogenerate -m "Create initial tables"
            

              
                Copy
              
            
          

See loob uue migratsiooniskripti kataloogi `alembic/versions`. Skript sisaldab SQL-koodi, mis on vajalik teie SQLAlchemy mudelites defineeritud tabelite loomiseks.

Lipuga `-m` määratakse migratsiooni kirjeldav sõnum. See sõnum salvestatakse migratsiooni ajalukku ja võib olla abiks iga migratsiooni otstarbe mõistmisel.

Manuaalne migratsiooni loomine

Keerulisemate migratsioonide korral peate võib-olla skripti käsitsi looma. Tühja migratsiooniskripti loomiseks käivitage järgmine käsk:

            alembic revision -m "Add a new column"
            

              
                Copy
              
            
          

See loob uue migratsiooniskripti tühjade `upgrade` ja `downgrade` funktsioonidega. Peate need funktsioonid täitma sobiva SQL-koodiga, et migratsioon teostada.

Migratsiooniskriptide mõistmine

Alembicu migratsiooniskriptid on Pythoni failid, mis sisaldavad kahte peamist funktsiooni: `upgrade` ja `downgrade`. Funktsioon `upgrade` defineerib andmebaasi skeemile rakendatavad muudatused, samal ajal kui funktsioon `downgrade` defineerib muudatused, mis on vajalikud migratsiooni tagasivõtmiseks. Mõelge neile vastavalt kui "edasi" ja "tagasi" operatsioonidele.

Siin on näide lihtsast migratsiooniskriptist, mis lisab tabelisse uue veeru:

            """
Add a new column to the users table

Revision ID: 1234567890ab
Revises: None
Create Date: 2023-10-27 10:00:00.000000

"""
from alembic import op
import sqlalchemy as sa


revision = '1234567890ab'
revises = None
down_revision = None


def upgrade():
    op.add_column('users', sa.Column('email', sa.String(255), nullable=True))


def downgrade():
    op.drop_column('users', 'email')

            

              
                Copy
              
            
          

Selles näites kasutab `upgrade` funktsioon `op.add_column` funktsiooni uue veeru nimega `email` lisamiseks tabelisse `users`. Funktsioon `downgrade` kasutab `op.drop_column` funktsiooni veeru eemaldamiseks.

Alembic pakub mitmesuguseid operatsioone andmebaasi skeemide muutmiseks, sealhulgas:

• `op.create_table`: Loob uue tabeli.
• `op.drop_table`: Kustutab olemasoleva tabeli.
• `op.add_column`: Lisab tabelisse uue veeru.
• `op.drop_column`: Kustutab veeru tabelist.
• `op.create_index`: Loob uue indeksi.
• `op.drop_index`: Kustutab olemasoleva indeksi.
• `op.alter_column`: Muudab olemasolevat veergu.
• `op.execute`: Käivitab tooreid SQL-lauseid.

Migratsiooniskriptide kirjutamisel on oluline arvestada järgmisega:

• Idempotentsus: Migratsiooniskriptid peaksid olema idempotentsed, mis tähendab, et neid saab käivitada mitu korda, põhjustamata vigu või soovimatuid kõrvalmõjusid. See on eriti oluline automatiseeritud juurutuste puhul.
• Andmete säilitamine: Olemasolevate tabelite muutmisel peaksite püüdma andmeid võimalikult palju säilitada. Näiteks veeru ümbernimetamisel saate luua ajutise veeru, kopeerida andmed uude veergu ja seejärel vana veeru kustutada.
• Tehingud: Migratsiooniskriptid tuleks käivitada tehingu piires. See tagab, et kõik muudatused rakendatakse aatomiliselt ja et andmebaasi saab vea korral taastada eelnevasse olekusse.

Migratsioonide rakendamine

Kui olete oma migratsiooniskriptid loonud, saate neid oma andmebaasile rakendada, kasutades käsku `alembic upgrade`.

            alembic upgrade head
            

              
                Copy
              
            
          

See käsk rakendab kõik ootel olevad migratsioonid andmebaasile, viies selle uusima revisjonini. Argument `head` määrab, et Alembic peaks rakendama kõik migratsioonid kuni head revisjonini. Saate määrata ka konkreetse revisjoni, milleni uuendada.

Varasemale revisjonile tagasipöördumiseks saate kasutada käsku `alembic downgrade`.

            alembic downgrade -1
            

              
                Copy
              
            
          

See käsk viib andmebaasi ühe revisjoni võrra allapoole. Saate määrata ka konkreetse revisjoni, milleni tagasi pöörata.

Alembic jälgib, millised migratsioonid on andmebaasile rakendatud tabelis nimega `alembic_version`. See tabel sisaldab ühte rida, mis salvestab andmebaasi praeguse revisjoni.

Alembicu edasijõudnud tehnikad

Alembic pakub mitmeid edasijõudnud tehnikaid andmebaasi migratsioonide haldamiseks.

Hargnemised (Branches)

Hargnemised võimaldavad teil luua mitu paralleelset migratsioonijada. See võib olla kasulik rakenduse erinevate funktsioonide või versioonide paralleelseks arendamiseks.

Uue haru loomiseks kasutage käsku `alembic branch`.

            alembic branch feature_x
            

              
                Copy
              
            
          

See loob uue haru nimega `feature_x`. Seejärel saate sellel harul luua uusi migratsioone, kasutades käsku `alembic revision`.

            alembic revision -m "Add feature X" --branch feature_x
            

              
                Copy
              
            
          

Haru peaharu tagasi ühendamiseks saate kasutada käsku `alembic merge`.

            alembic merge feature_x -m "Merge feature X"
            

              
                Copy
              
            
          

Keskkonnad

Keskkonnad võimaldavad teil konfigureerida Alembicut erinevalt erinevate keskkondade jaoks, nagu arendus, testimine ja tootmine. See võib olla kasulik erinevate andmebaasi ühenduste kasutamiseks või erinevate migratsioonide rakendamiseks igas keskkonnas.

Uue keskkonna loomiseks saate luua iga keskkonna jaoks eraldi Alembicu konfiguratsioonifaili. Näiteks saate luua `alembic.dev.ini` faili arenduskeskkonna jaoks ja `alembic.prod.ini` faili tootmiskeskkonna jaoks.

Seejärel saate Alembicu käskude käivitamisel lipuga `-c` määrata, millist konfiguratsioonifaili kasutada.

            alembic upgrade head -c alembic.dev.ini
            

              
                Copy
              
            
          

Kohandatud operatsioonid

Alembic võimaldab teil defineerida oma kohandatud operatsioone andmebaasi skeemide muutmiseks. See võib olla kasulik keerukate või mittestandardsete andmebaasi operatsioonide sooritamiseks.

Kohandatud operatsiooni loomiseks peate defineerima uue klassi, mis pärib klassist `alembic.operations.Operation`. See klass peaks defineerima meetodid `upgrade` ja `downgrade`, mida kutsutakse, kui operatsiooni rakendatakse või tagasi võetakse.

Seejärel peate registreerima kohandatud operatsiooni Alembicuga, kasutades meetodit `alembic.operations.Operations.register_operation`.

Parimad tavad andmebaasi migratsioonide jaoks

Siin on mõned parimad tavad, mida andmebaasi migratsioonidega töötamisel järgida:

• Testige oma migratsioone: Testige oma migratsioone alati mitte-tootmiskeskkonnas enne nende rakendamist tootmisandmebaasile. See aitab teil vigu tabada ja andmete kadu vältida.
• Kasutage kirjeldavaid migratsiooniteateid: Kasutage migratsioonide loomisel selgeid ja kirjeldavaid sõnumeid. See hõlbustab iga migratsiooni otstarbe mõistmist tulevikus.
• Hoidke migratsioonid väikesed ja keskendunud: Hoidke oma migratsioonid väikesed ja keskenduge ühele muudatusele. See hõlbustab vajadusel üksikute migratsioonide tagasivõtmist.
• Kasutage tehinguid: Käivitage oma migratsioonid alati tehingu piires. See tagab, et kõik muudatused rakendatakse aatomiliselt ja et andmebaasi saab vea korral taastada eelnevasse olekusse.
• Dokumenteerige oma migratsioonid: Dokumenteerige oma migratsioonid kommentaaride ja selgitustega. See hõlbustab teistel arendajatel teie andmebaasi skeemi mõistmist ja hooldamist.
• Automatiseerige oma migratsioonid: Automatiseerige oma migratsioonid osana oma rakenduse juurutustorustikust. See tagab, et teie andmebaas on alati teie rakenduse koodiga sünkroonis.
• Kaaluge andmete säilitamist: Olemasolevate tabelite muutmisel kaaluge alati, kuidas andmeid võimalikult palju säilitada. See võib vältida andmete kadu ja minimeerida häireid teie kasutajatele.
• Varundage oma andmebaas: Varundage oma andmebaas alati enne migratsioonide rakendamist tootmiskeskkonda. See võimaldab teil taastada oma andmebaasi eelnevasse olekusse, kui midagi valesti läheb.

Järeldus

Andmebaasi migratsioonid on kaasaegse tarkvaraarenduse oluline osa. Kasutades Alembicut koos SQLAlchemy-ga, saate tõhusalt hallata oma andmebaasi skeemi, jälgida muudatusi ja automatiseerida värskendusi. See juhend on andnud teile põhjaliku ülevaate Alembicust ja selle funktsioonidest. Järgides siin kirjeldatud parimaid tavasid, saate tagada, et teie andmebaasi migratsioonid on usaldusväärsed, hooldatavad ja turvalised.

Ärge unustage regulaarselt harjutada ja uurida Alembicu täiustatud funktsioone, et omandada andmebaasi skeemi tõhusa haldamise oskus. Teie projektide arenedes muutub teie arusaam andmebaasi migratsioonidest hindamatuks varaks.

See juhend on mõeldud alguspunktiks. Täpsema teabe saamiseks vaadake ametlikke SQLAlchemy ja Alembicu dokumentatsioone. Head migreerimist!